<html>
  <body>
    The <a href="http://orkut.com">orkut</a> client library allows access to read and update <a href="http://orkut.com">orkut</a>'s social data. The client library is "experimental" at present and may change in the future. You can download the latest version of the client library <a href="http://code.google.com/p/orkut-os-client/">here</a>.
    Checkout the latest javadoc for this project <a href="http://orkut-os-client.googlecode.com/hg/java/doc">here</a>.

    <p>
    The Orkut Client Library API is broadly divided into the following classes:
    <ul>
      <li><b>Data Models</b>: These are java objects that represent content fetched from orkut. With an interface much like java-beans, they make it easy for a developer to access orkut's data.
        eg. see {@link com.google.orkut.client.api.OrkutPerson}, which represents a person's data on orkut</li>
      <li><b>Transactions</b>: These are individual operations which execute to produce a desired effect
        - like fetching information about a user ({@link com.google.orkut.client.api.GetProfileTx}) or updating a user's profile ({@link com.google.orkut.client.api.UpdateProfileTx})
      </li>
      <li><b>Transaction Factories</b>: All transactions are generated through transaction factories. Transaction factories usually provide a means to generate related transactions.
        eg. An Albums Transaction factory ({@link com.google.orkut.client.api.AlbumsTxFactory}) gives all transactions to create / delete / update and fetch albums.
      </li>
      <li><b>Batch Transaction and common constants</b>: A {@link com.google.orkut.client.api.BatchTransaction} collates multiple transactions as one transaction are provides a single request which can be sent to the orkut server.
        Common constants used in forming requests and understanding responses are in {@link com.google.orkut.client.api.Constants}</li>
    </ul>

    <p>A typical way to use the orkut client library is as follows:</p>

    <pre>

      // one time initializations:
      //   create a BatchTransaction and factories of choice
      BatchTransaction bt = new BatchTransaction();
      ProfileTxFactory profileFactory = new ProfileTxFactory();
      AlbumsTxFactory albumsFactory = new AlbumsTxFactory();

      // create the transactions
      // get the logged in user's profile
      GetProfileTx profileTx = profileFactory.getSelfProfile();
      // get first 50 albums of the logged in user
      GetAlbumsTx albumsTx = albumsFactory.getAlbums(Constants.USERID_ME);

      // add transactions to batch
      bt.add(profileTx).add(albumsTx);

      // send the request with 3-legged authorization and get response
      String requestBody = bt.getRequestBody();
      String contentType = bt.getContentType();
      String versionHeaderName = bt.getHttpVersionHeaderName();
      String versionHeaderValue = bt.getHttpVersionHeaderValue();

      // see sample app for an eg. of how 3 legged oauth is done
      String response = getResponseForRequest(contentType, versionHeaderName,
          versionHeaderValue, requestBody);
      bt.setResponse(response);

      // transactions now have the response data
      if (profileTx.hasErrors() || albumsTx.hasErrors()) {
        // handle errors
        return; // perhaps?
      }

      // do whatever with the data
      OrkutPerson profile = profileTx.getProfile();
      String givenName = profile.getGivenName();
      System.out.println("Hello, " + givenName);

      for (int i = 0; i < albumsTx.getAlbumCount(); i++) {
        Album album = albumsTx.getAlbum(i);
        String title = album.getTitle();
        int numPhotos = album.getNumPhotos();
        String thumbNail = album.getThumbnailUrl();

        System.out.println("Album: " + title + " has " + numPhotos + " photo(s)");
      }
    </pre>

    For more examples, see the samples in <code>java/sample/sample-src</code> directory.
  </body>
</html>
